Release 10.1A: OpenEdge Development:
Progress 4GL Reference

ADD-SUPER-PROCEDURE( ) method

Associates a super procedure file with a procedure file or with the current OpenEdge session. When a procedure file invokes an internal procedure or a user-defined function, Progress searches for it, among other places, in the super procedures (if any) of the procedure file and of the current OpenEdge session. The procedure-search option determines which procedures are searched.

For more information on the rules that Progress uses to search for internal procedures and user-defined functions, see the "Search rules" section. For information on super procedures, see OpenEdge Development: Progress 4GL Handbook . For a sample program that uses the ADD-SUPER-PROCEDURE method, see the reference entry for the RUN SUPER statement in this book.

Returns FALSE for a Web service procedure.

Return type: LOGICAL

Applies to: SESSION system handle, THIS-PROCEDURE system handle and all procedure handles

Syntax

ADD-SUPER-PROCEDURE ( super-proc-hdl [ , proc-search ] )

super-proc-handle

The handle of a running persistent procedure that you want to make a super procedure of the local procedure or of the current OpenEdge session.

ADD-SUPER-PROCEDURE returns FALSE if super-proc-hdl is not a valid handle, or if Progress detects that the method was not successful. Otherwise, the method returns TRUE.

proc-search

Optional expression that determines which super procedures are searched when super-proc-hdl invokes RUN SUPER or the SUPER function. Valid values are SEARCH-SELF (or 1) or SEARCH-TARGET (or 2). The default, if there is no entry, is SEARCH-SELF. The search commences in the super procedure stack of super-proc-hdl.

Consider the following:

SEARCH-SELF starts searching in the procedure file that initiated the current internal procedure or user-defined function.
SEARCH-TARGET starts searching the super procedures of the procedure file that originally invoked the current internal procedure or user-defined function (the procedure with the original RUN statement). If the procedure was RUN . . . IN procedure-handle, SEARCH-TARGET searches the super procedures of procedure-handle.
A given super-proc-hdl can be added as either SEARCH-TARGET or SEARCH-SELF, but cannot be added as both. If proc-search is set for a super-proc-hdl, then any attempt to change its value generates a run-time warning, but the ADD-SUPER-PROCEDURE( ) method succeeds. The warning message “Changing proc-search-string for procedure <.p-name> from <string> to <string>” is presented to indicate that the application is using an instance of a given super procedure in an inconsistent manner. This warning message can be suppressed by using the SESSION:SUPPRESS-WARNINGS attribute. In addition, the warning message can be avoided by creating two instances of super-proc-hdl, one identified as SEARCH-TARGET and the other identified as SEARCH-SELF.

Associating a super procedure with a procedure

The following example associates a super procedure with the current procedure:

THIS-PROCEDURE:ADD-SUPER-PROCEDURE(my-super-proc-hdl,SEARCH-SELF).

The following example:

Associates a super procedure with a procedure that the current procedure is working for.
Requests that the super procedure stack associated with local-proc-hdl be searched rather than the stack associated with my-super-proc-hdl when RUN SUPER is invoked in super-proc-hdl.

local-proc-hdl:ADD-SUPER-PROCEDURE(my-super-proc-hdl,SEARCH-TARGET).

The procedure to which you add a super procedure is called the local procedure of the super procedure.

Associating a super procedure with the current OpenEdge session

The following example associates a super procedure with the current OpenEdge session:

SESSION:ADD-SUPER-PROCEDURE(my-super-proc-hdl).

When you do this, Progress automatically associates the super procedure with all the session’s procedures—persistent and nonpersistent—without your having to change their code in any way. This technique lets you replace occurrences of the following:

THIS-PROCEDURE:ADD-SUPER-PROCEDURE(super-proc-hdl).

in individual procedures with a single occurrence of the following:

SESSION:ADD-SUPER-PROCEDURE(super-proc-hdl).

Super procedure stacking

You can associate multiple super procedures with a single local procedure or with the current OpenEdge session. When you do this, Progress stores (and later on, searches) the corresponding procedure handles in last in first out (LIFO) order—the handle of the most recently added super procedure first, the handle of the next most recently added super procedure second, etc.

A collection of super procedure handles associated with a local procedure or with the current OpenEdge session is called a super procedure stack. The handle of the most recently added super procedure occupies the top of the stack.

If you add a super procedure that is already in the stack, Progress removes the previous occurrence of the super procedure handle from the stack and adds the new occurrence to the top of the stack—all without reporting an error.

Super procedure chaining

You can add a super procedure to a super procedure. For example, imagine the following scenario:

A, B, and C are procedure files running persistently.
B is a super procedure of A.
C is a super procedure of B.

B is a super procedure (of A) and has a super procedure (C).

When you add a super procedure to a super procedure, the result is a super procedure chain, each link of which consists of two elements: a local procedure and its super procedure. When Progress searches a super procedure chain, it does not proceed to the next link unless the current link’s super procedure element explicitly invokes its super version (by using the RUN SUPER statement or the SUPER function).

For example, imagine the following scenario:

A, B, and C, and X are procedure files running persistently.
add-record is an internal procedure different versions of which reside in A, B, and C.
B is a super procedure of A.
C is a super procedure of B.
X says RUN add-record IN A.

The following events occur:

Progress searches A for add-record and runs it if found.
If and only if A’s add-record exists and says RUN SUPER, Progress searches B for add-record and runs it if found.
Note: If A does not contain add-record, the following events occur: If B contains add-record, Progress runs it. If B does not contain add-record, Progress does not search for add-record in C.
If and only if B’s add-record exists and says RUN SUPER, Progress searches C for add-record and runs it if found.

In this way, Progress avoids excessive and possibly circular searching.

Search rules

Progress searches for internal procedures and user-defined functions depending on how the internal procedure or user-defined function is invoked. The search rules illustrated in the first three cases assume that all the super procedures were added with no proc-search value or with a proc-search value of SEARCH-SELF. The fourth case illustrates the search process when a super procedure is added with a proc-search value of SEARCH-TARGET:

Case 1: When Progress encounters a statement like the following:

RUN add-record(’customer’).

Progress searches for add-record as follows:

As an internal procedure in the local procedure.
As an internal procedure in a super procedure of the local procedure.
As an internal procedure in a super procedure of the OpenEdge session.
As an external procedure file add-record.p or add-record.r.

Case 2: When Progress encounters a statement like the following:

RUN add-record(’customer’) IN my-proc-hdl.

Progress searches for add-record as follows:

As an internal procedure in my-proc-hdl.
As an internal procedure in a super procedure of my-proc-hdl.
As an internal procedure in a super procedure of the OpenEdge session.

Case 3: When Progress encounters a statement like the following:

add-record(’customer’).

Progress searches for add-record as follows:

As a user-defined function in the local procedure.
As a user-defined function in a super procedure of the local procedure.
As a user-defined function in a super procedure of the OpenEdge session.
Note: The rules of Case 3 apply whether or not the user-defined function’s declaration (function prototype) includes the IN proc-hdl option. In Case 3, proc-hdl represents the local procedure. For more information on function prototypes of user-defined functions, see OpenEdge Development: Progress 4GL Handbook .

Search rules for SEARCH-TARGET

Case 4: A procedure, main.p, has added three super procedures, S1, S2, and S3 (in that order). Each of these super procedures has added its own super procedures, S1A, S1B, S2A, S2B, S3A, S3B. The procedure, add-record, exists in three places: in S1, in S2 where it contains a RUN SUPER statement, and in S2A.

When Progress encounters a statement like "RUN add-record(’customer’).", it searches for the add-record procedure:

As an internal procedure in the local procedure, main.p.
Then as an internal procedure in S3, and then in S2 where it is found.

If add-record was added with no proc-search value or with a proc-search value of SEARCH-SELF, when RUN SUPER is executed within add-record in S2, Progress starts searching in S2A, which is next in the search stack of the super procedure S2.

If add-record was added with a proc-search value of SEARCH-TARGET, when RUN SUPER is executed within add-record in S2, Progress will start searching in S1 which is next in the search stack of the local procedure, main.p.

Note: The search commences with the super procedure following super-proc-hdl in the local procedure’s chain.